home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 2 / Apprentice-Release2.iso / Source Code / C / Snippets / File Access Examples 1.0 / Opening&ClosingFiles.txt < prev    next >
Encoding:
Text File  |  1994-10-25  |  9.1 KB  |  237 lines  |  [TEXT/KAHL]
  1. /* An introduction to opening/closing Macintosh files and the
  2.  * Standard File Package.
  3.  *
  4.  * Hi. I'm Ken Worley of Apt Ideas Software. I can be reached
  5.  * on America Online or eWorld at KNEworley or via the internet at
  6.  * KNEworley@eworld.com.
  7.  *
  8.  * FORKS
  9.  *
  10.  * One thing you should know is that each Macintosh file has two
  11.  * forks: the data fork and the resource fork. These forks are accessed
  12.  * just like different files for the most part except for the fact
  13.  * that a file cannot have ONLY a resource fork. Files have either
  14.  * a data fork only (you can still add a resource fork), or both forks.
  15.  * When you create a new file, it has a data fork only. You have to
  16.  * use the FSpCreateResFile function to add a resource fork (Actually
  17.  * this creates a resource map which allows resource access). Once a
  18.  * file has a resource map, you access it like a separate file
  19.  * using the FSpOpenResFile function to open the file and other
  20.  * Resource Manager calls to read in and save resources.
  21.  *
  22.  * Of course, you can access resources in the same file your
  23.  * application code is stored in without explicitly opening the
  24.  * file. The system has already made that file the current
  25.  * open resource file because it reads your code resources from it.
  26.  *
  27.  * MACINTOSH FILE OPENING/CLOSING/SPECIFYING
  28.  *
  29.  * The functions in this file don't deal with opening/closing files,
  30.  * so here's a brief explanation of the toolbox routines used to
  31.  * accomplish those tasks:
  32.  *
  33.  *        OPENING AN EXISTING FILE
  34.  *
  35.  *        pascal void StandardGetFile( FileFilterProcPtr fileFilter,
  36.  *                                    short numTypes, SFTypeList typeList,
  37.  *                                    StandardFileReply *reply );
  38.  *
  39.  *        StandardGetFile is used to present the user with a standard
  40.  *        dialog box asking the user to select a file to use/open.
  41.  *        The parameters are used as follows:
  42.  *
  43.  *            fileFilter        Usually just set to NULL, you can specify
  44.  *                            the address of a filter procedure for
  45.  *                            more complex filtering of which files
  46.  *                            appear in the list the user chooses from.
  47.  *            numTypes        The number of types specified in the
  48.  *                            typeList. If you send -1 for this parameter,
  49.  *                            all files are shown.
  50.  *            typeList        An array of 4 values of type OSType that
  51.  *                            specify which types of files can be opened
  52.  *                            by the application and thus, which files
  53.  *                            should appear in the list presented to the
  54.  *                            user. Elements are usually set manually
  55.  *                            like this: myTypes[0] = 'Ttxt'; If you
  56.  *                            specified 2 in numTypes, your types should
  57.  *                            be stored in elements 0 and 1.
  58.  *            *reply            A pointer to a standard file reply record
  59.  *                            which specifies the file selected by the
  60.  *                            user (if any).
  61.  *
  62.  *        StandardGetFile is usually used like this:
  63.  *
  64.  *            SFTypeList            myTypes;
  65.  *            short                noOfTypes;
  66.  *            StandardFileReply    myReply;
  67.  *
  68.  *            myTypes[0] = 'myTp';
  69.  *            noOfTypes = 1;
  70.  *            StandardGetFile( NULL, noOfTypes, myTypes, &myReply );
  71.  *
  72.  *        The record myReply contains the following useful fields which
  73.  *        are filled in after a call to StandardGetFile:
  74.  *
  75.  *            Boolean        sfGood        This field contains true if the user
  76.  *                                    actually selected a file (not CANCEL).
  77.  *            OSType        sfType        The type of the file selected by
  78.  *                                    the user.
  79.  *            FSSpec        sfFile        The file specification record of the
  80.  *                                    file selected by the user.
  81.  *            and other fields useful in specific other situations...See
  82.  *            Inside Macintosh:Files for more info.
  83.  *
  84.  *        To open the file specified, you use the FSpOpenDF procedure.
  85.  *
  86.  *        pascal OSErr FSpOpenDF( FSSpec* spec,
  87.  *                                SignedByte permission, short *refNum );
  88.  *
  89.  *        The DF stands for data fork (there is also an FSpOpenRF function).
  90.  *        FSpOpenDF opens the existing Macintosh file specified by the
  91.  *        parameters.  If you'd just called StandardGetFile as in the above
  92.  *        example, you would call FSpOpenDF as follows:
  93.  *
  94.  *            OSErr        myErr;
  95.  *            short        myFileRef;
  96.  *
  97.  *            if ( myReply.sfGood )        /* if user didn't cancel */
  98.  *                myErr = FSpOpenDF( &myReply.sfFile,
  99.  *                                    fsRdWrPerm, &myFileRef );
  100.  *
  101.  *        If there is a problem opening the specified file, an error value
  102.  *        will be returned in myErr. Otherwise, noErr is returned. After
  103.  *        the call to HOpen, the parameter myFileRef contains the open file's
  104.  *        reference number. This number is used to refer to the file as long
  105.  *        as it's open to read and write data.
  106.  *
  107.  *        Some of the possible errors are:
  108.  *
  109.  *            nsvErr                no such volume
  110.  *            ioErr                input/output error
  111.  *            bdNamErr            bad filename error
  112.  *            fnfErr                file not found error
  113.  *            opWrErr                file already open for writing error
  114.  *            permErr                attempt to open locked file for writing
  115.  *            dirNFErr            directory not found error
  116.  *            see Inside Macintosh:Files for other errors
  117.  *
  118.  *        The permission parameter can hold any one of these constants which
  119.  *        determine whether the file is opened for reading only, writing only,
  120.  *        or for both reading and writing:
  121.  *
  122.  *            fsCurPerm        whatever is allowed
  123.  *            fsRdPerm        read only permission
  124.  *            fsWrPerm        write only permission
  125.  *            fsRdWrPerm        read/write permission
  126.  *            fsRdWrShPerm    shared read/write permission
  127.  *
  128.  *        CREATING A NEW FILE
  129.  *
  130.  *        Of course, if you want to create a new file, not open an existing
  131.  *        one, you can use StandardPutFile:
  132.  *
  133.  *        pascal void StandardPutFile( const Str255 prompt,
  134.  *                                    const Str255 defaultName,
  135.  *                                    StandardFileReply *reply );
  136.  *
  137.  *        StandardPutFile is used to present the user with a standard
  138.  *        dialog box asking the user to specify a location and a filename
  139.  *        for a file to be saved/created.
  140.  *        The parameters are used as follows:
  141.  *
  142.  *            prompt            A string which appears just over the filename
  143.  *                            field in the dialog. Usually something like:
  144.  *                            "Save as:".
  145.  *            defaultName        The string that initially appears in the
  146.  *                            filename field of the dialog. This may be an
  147.  *                            empty string specified as "\p".
  148.  *            *reply            A pointer to a standard file reply record
  149.  *                            which contains info about the file specified
  150.  *                            by the user (if any).
  151.  *
  152.  *        StandardPutFile is usually used like this:
  153.  *
  154.  *            StandardFileReply    myReply;
  155.  *
  156.  *            StandardPutFile( "\pSave as:", "\p", &myReply );
  157.  *
  158.  *        The record myReply contains the following useful fields which
  159.  *        are filled in after a call to StandardPutFile:
  160.  *
  161.  *            Boolean        sfGood        This field contains true if the user
  162.  *                                    actually specified a file (not CANCEL).
  163.  *            Boolean        sfReplacing    This field contains true if the file
  164.  *                                    name and location specified by the
  165.  *                                    user is already in use and the user
  166.  *                                    wishes to overwrite the existing file.
  167.  *                                    StandardPutFile has already presented
  168.  *                                    the user with a dialog asking if s/he
  169.  *                                    really wants to replace the file.
  170.  *            ScriptCode    sfScript    The script of the file specified
  171.  *                                    (This has to do with languages and
  172.  *                                    the Text Services Manager.)
  173.  *            FSSpec        sfFile        The file specification record of the
  174.  *                                    file specified by the user.
  175.  *            and other fields useful in specific other situations...See
  176.  *            Inside Macintosh:Files for more info.
  177.  *
  178.  *        The record contains no information about file type because,
  179.  *        since you're creating a new file, you'll specify whatever type you
  180.  *        want when you actually create the file.
  181.  *
  182.  *        pascal OSErr FSpCreate( FSSpec *spec, OSType creator,
  183.  *                                OSType fileType, ScriptCode scriptTag );
  184.  *
  185.  *        FSpCreate actually creates a new file based on the information
  186.  *        in the spec parameter. The file has the file creator and types
  187.  *        specified in the parameters. The scriptTag parameter relates to
  188.  *        languages other than English and the Text Services Manager.
  189.  *        Most apps will use either the constant smSystemScript or the
  190.  *        value returned in the sfScript field of a reply record from
  191.  *        StandardPutFile for this parameter.
  192.  *
  193.  *        If you'd called StandardPutFile as in the above example, you
  194.  *        might call FSpCreate like this:
  195.  *
  196.  *            OSErr        myErr;
  197.  *
  198.  *            if ( myReply.sfReplacing )
  199.  *                myErr = FSpDelete( &myReply.sfFile );
  200.  *
  201.  *            myErr = FSpCreate( &myReply.sfFile, 'TTxt', 'TEXT',
  202.  *                                myReply.sfScript );
  203.  *
  204.  *        Note that in the example, if we are replacing an existing file,
  205.  *        we manually delete that file first using the FSpDelete function.
  206.  *        In an actual program, you'd want to check the error value
  207.  *        returned by FSpDelete to make sure it's noErr.
  208.  *
  209.  *        Of course, after we create the file, we then need to open it
  210.  *        with FSpOpenDF just as in the example above for already existing
  211.  *        files. Calling FSpCreate does NOT open the file.
  212.  *
  213.  *        Some of the possible errors FSpCreate might return are:
  214.  *
  215.  *            dirFulErr            file directory full error
  216.  *            dskFulErr            disk full error
  217.  *            nsvErr                no such volume
  218.  *            ioErr                input/output error
  219.  *            bdNamErr            bad filename error
  220.  *            fnfErr                directory not found error
  221.  *            dirNFErr            directory not found error
  222.  *            wPrErr                volume is write protected by hardware
  223.  *            vLckdErr            volume is locked by software
  224.  *            see Inside Macintosh:Files for other errors
  225.  *
  226.  *        CLOSING A FILE
  227.  *
  228.  *        Closing a file is simple. You just call FSClose with the reference
  229.  *        number of an open file. If you'd opened a file with FSpOpenDF as
  230.  *        in the above example, you'd close it like this:
  231.  *
  232.  *            myErr = FSClose( myFileRef );
  233.  *
  234.  *    It's as simple as that!
  235.  */
  236.  
  237.